IRIX Base Documentation 2002 November

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat5 / elspec.z / elspec

Wrap

Text File | 2002-10-03 | 23.4 KB | 630 lines

ELSPEC(5) Last changed: 4-6-99 NNAAMMEE eellssppeecc - ELF layout specification IIMMPPLLEEMMEENNTTAATTIIOONN IRIX systems DDEESSCCRRIIPPTTIIOONN This man page describes the ELF Layout Specification (ELSPEC) language implemented by lldd(1). ELSPEC allows users to specify the exact layout of object files, programs, and shared objects. It is often desirable to specify the exact layout of an executable file. Some of the uses of this might be embedded systems layout, thread-local data layout, reducing cache conflicts, reducing false sharing, reducing memory utilization. IINNVVOOKKIINNGG LLAAYYOOUUTT SSPPEECCIIFFIICCAATTIIOONN An ELSPEC file can be specified to the linker on the compiler command line using the --WWll option and the lldd(1) command's --eellssppeecc option. The following examples shows the cccc(1) and lldd(1) commands specifying an ELSPEC file: cc -Wl,-elspec,_e_l_s_f_i_l_e ...... or ld -elspec _e_l_s_f_i_l_e ...... You can get a sample ELSPEC file for the default link by using the lldd(1) command's --eellssmmaapp option. The following example shows the cccc(1) and lldd(1) commands with the --eellssmmaapp option: cc -Wl,-elsmap ... or ld -elsmap ... BBAASSIICC BBUUIILLDDIINNGG BBLLOOCCKKSS The basic units that the linker manipulates are called _i_n_p_u_t _s_e_c_t_i_o_n_s. Each object file can have several input sections with familiar names such as ..tteexxtt, ..ddaattaa, ..bbssss, and so on. The correctness of compiled code can depend on the exact layout of code and data within a section, but it never depends on the relative layout between sections. For that reason, the linker does not rearrange or change the contents of any individual input section with the exception of uninitialized common variables. Uninitialized common variables, for which space is allocated by the linker, are not allocated to any input section. These can be manipulated freely, but they cannot be split into pieces by an ELSPEC. You get a COMMON variable by using a Fortran COMMON statement or from C data variables declared at file scope in files that have been compiled with either ..BB --cccckkrr or ..BB --ccoommmmoonn. SSeeggmmeennttss Input sections are linked together contiguously into output sections. Output sections are organized in an ELF file into loadable segments specified in the program header. For more information, see the eellff(4) man page. Segments represent a contiguous portion of the file to be loaded into memory as it is, with possibly the addition of extra memory at the end. PPLLAACCEEMMEENNTT RRUULLEESS An ELSPEC allows you to specify the following: * The placement of input sections within output sections. * The placement of output sections within segments. Rules exist regarding default placement. The following rules describe when a section from an input file is placed in the output file: 1. If the section (and object and archive) is mentioned explicitly, it is placed as specified. 2. If there is a section specified in the map with the same name, with ddeeffaauulltt as one of its contents, and with matching attributes, it is placed there. The input section maintains its layout position relative to other listed contents. If there is more than one default-placed input section, space is allocated for them in the order encountered. If the attributes of the input section do not match those specified in the map, it is an error. 3. If there is a segment specified in the map with matching attributes that has specified ddeeffaauulltt as one of its contents, the input section is placed in an output section with the same name and attributes. The input section maintains its layout position relative to other listed contents. If there is more than one default-placed input section, space is allocated for them in the order encountered. If the attributes of the input section do not match those specified in the map or those of another default input section, it is an error. 4. If an input object is listed as a segment content without mention of specific input sections, all sections with appropriate attributes are merged by name and laid out in the order encountered. 5. The linker manages file layout in any fashion it sees fit. 6. Specifying hheeaaddeerrss or specifying ddeeffaauulltt as contents of a segment allows (but does not require) the inclusion of headers, such as the ELF header and the program header, into that segment. Specifying nnoohheeaaddeerrss forbids the inclusion of headers into that segment 7. Linker-generated sections are placed into a segment with matching attributes that has llddggeenn specified as its segment contents. Specific linker-generated sections can be placed by using $$llddoobbjj as the object name. When a non-optional, linker-generated section has no place to be loaded, an error is generated unless the $$iiggnnoorreellddggeenn ELSPEC variable is set to ttrruuee. For more information, see the EELLSSPPEECC VVaarriiaabblleess section in this man page. 8. Command line options are available to override the general rules stated on this man page. 9. Overlaps in virtual space or physical space are reported unless at least one of the segment descriptions has specified an overlap with the other, or unless the $$iiggnnoorreeoovveerrllaappss ELSPEC variable is set to ttrruuee. 10.The name, type, and flags of an output section uniquely determine a section. Specifying more than one such section in the file yields unpredictable results. SSYYNNTTAAXX The following sections describe the syntax of an ELSPEC file. OOvveerrvviieeww An ELSPEC file consists of the following parts, in the following order: 1. A list of global variable settings 2. A list of symbol attribute specifications 3. A list of segment specifications Using modified Backus-Naur Form (BNF), this can be depicted as follows: <layoutspec> ::= <globals> <symlist> <seglist>; SSeeggmmeennttss Segments are the basic runtime building blocks and are comprised of one or more sections. The content of each segment is contiguous. Sections within a segment must have compatible attributes. The following BNF shows how a segment is organized: <segdef> ::= beginseg <segname> <segattr> contents <segcontents> endseg ; <segname> ::= /* empty */ | <idstring> ; <segattr> ::= /* empty */ | <segattr> segtype <segtype> | <segattr> vaddr <address> | <segattr> paddr <address> | <segattr> filesz <size> | <segattr> memsz <size> | <segattr> segflags <segflags> | <segattr> segalign <number> | <segattr> prepad <number> ; WHERE: "segtype" is the segment type (see the following BNF for <segtype>). "vaddr" is the virtual address. "paddr" is the physical address. "filesz" is the size of the segment in the file. "memsz" is the size of the segment at runtime in memory. "segflags" is the bit mask of flags for this segment (see the following BNF for <segflags>). "segalign" is the alignment of the segment. "prepad" is the amount of padding to put at the beginning of the segment. <segtype> ::= noload | <number> | LOAD | REL ; WHERE: "noload" indicates that the section should not be loaded at runtime. This is a pseudo segment used to group nonloadable sections. "<number>" is the hexadecimal number for the section type. See the ELF ABI for possible segment types. "LOAD" indicates that the segment should be loaded at runtime. DEFAULT. "REL" indicates relocatable output. See the following <segflags>. <segflags> ::= /* empty, default settings are RWX */ | <segflags> R | <segflags> W | <segflags> X | <segflags> L ; WHERE: "R" is readable. "W" is writable. "X" is executable. "L" is thread local. SSeeggmmeenntt CCoonntteennttss The contents of a segment are usually in the form of output sections. These section are further specified to contain input sections (see following) and are laid out in the order specified, building upwards in virtual address space. The segment contents (sseeggccoonntteennttss) are defined as follows: <segcontents> ::= /* empty */ | <segcontents> <outsection> | <segcontents> noheaders | <segcontents> default | <segcontents> default_gprel | <segcontents> ldgen ; WHERE: "<outsection>" is a specific output section. For more information, see the Output Sections section of this man page. "noheaders" excludes ELF, PROGRAM, and SECTION headers. "default" allows the linker to place input sections with compatible attributes that are not otherwise mentioned in the current segment. This is accomplished by creating distinct output sections for each unique set of section type, flags, and section name, and placing it in the best segment that has specified "default" as one of its segment contents. "default_gprel" specifies all output sections that are GP-relative. GP is the Global Pointer. "ldgen" consists of linker-generated output sections. OOuuttppuutt SSeeccttiioonnss Output sections are a convenient way to group material within a segment. For example, if you have decided to have read-only data and program text in the same segment, but within that segment, you want to have all the read-only data together and all the text together. You can define two output sections, named ..rrddaattaa and ..tteexxtt, and place them both within a single segment. Most of the terms used in the section syntax maps to the ELF section header structure fields, which are as follows: FFiieelldd nnaammee CCoonntteenntt sshh__nnaammee Section name sshh__ttyyppee Section type sshh__ffllaaggss Section flags sshh__aaddddrr Address of first byte, or zero sshh__ooffffsseett File offset of section sshh__ssiizzee Section's size in bytes sshh__lliinnkk Table index link (section specific) sshh__iinnffoo Extra information (section specific) sshh__aaddddrraalliiggnn Address alignment constraint sshh__eennttssiizzee Size of fixed-size entries in section, or zero The output sections are defined as follows: <outsection> ::= beginscn <idstring> <scnattr> <scnspecial> <scncontents> endscn | beginscn <idstring> relfor <idstring> endscn | beginscn <idstring> relafor <idstring> endscn ; <scnattr> ::= /* empty string */ | <scnattr> scntype <scntype> | <scnattr> scnflags <scnflags> | <scnattr> scnsize <size> | <scnattr> link <number> | <scnattr> info <number> | <scnattr> scnalign <number> | <scnattr> entsize <number> ; <scntype> ::= PROGBITS | NOTE | NOBITS | <number> ; WHERE: "PROGBITS" means the section will be in memory at runtime. "NOTE" means the section with marked as note section. "NOBITS" means the contents of the section may not take up any space in the file, but it is filled out at runtime. "<number>" is the hexadecimal number that represents the section type. (See the MIPS ABI). <scnflags> ::= <scnflaglist> | <number> | none ; <scnflaglist> ::= /* empty */ | <scngflaglist> WRITE | <scnflaglist> ALLOC | <scnflaglist> EXECINSTR | <scnflaglist> GPREL | <scnflaglist> MERGE | <scnflaglist> NOSTRIP | <scnflaglist> LOCAL ; WHERE: "WRITE" means that the contents are writable. "ALLOC" means that the contents will be in memory. "EXECINSTR" means that the contents are executable instrutions. "GPREL" means that the contents are within 64K bytes of the value contained in the GP register (short data). "MERGE" means that the contents of the section can be merged with other similar sections. For example, literal sections. "NOSTRIP" means that this section should not be stripped from the file. "LOCAL" means that the contents are thread-local data. Layout specification for relocatable links is supported; for information on these see the --rr option on the lldd(1) man page. Unlike other types of output sections, the contents of relocation sections cannot be freely specified. Rather, the contents of a given rreellffoorr section are determined relative to some other output section. For example, the following section contains all the rel-type relocations for the output section named ..mmyytteexxtt: beginscn .rel.mytext relfor .mytext endscn Relocation sections can be given any name, but the relocation must be preceded by the section to which the relocations are relative. IInnppuutt sseeccttiioonnss Input sections are the basic building blocks that the linker manipulates. Each object file read by the linker can contain several of these input sections. The ELSPEC file works by specifying the arrangement of these input sections. You can specify input sections by either attempting to specify the section directly or by specifying an external symbol name. Specifying an external symbol name has the effect of specifying the section in which that symbol definition resides. These two methods of specification are defined as follows: <item> ::= <inputscn> | <symspec> ; Sometimes the attributes of an input section are not compatible with those of the enclosing output section. In the BNF that follows, you see different input section specifications categorized as either specific or generic. Conflicts are handled as follows: * If a specific mention conflicts with default output section attributes, the output section attributes are promoted to be compatible. * If a specific mention conflicts with user-specified output section attributes, the input section is included with a warning, but the output section attributes are not altered. * If a generic mention conflicts with output section attributes, the input section is not included in the output section, regardless of whether the output sections attributes were user-specified or not. In the following BNF, the <<iiddssttrriinngg>> specifies the name of the input section. If no name is specified, all sections from the mentioned object with matching attributes are selected. <inputscn> ::= sec <idstring> /* specific mention */ | sec <idstring> in <object> /* specific mention */ | <object> /* generic mention */ ; <object> ::= obj[ect] <idstring> ( <idstring> ) | obj[ect] <idstring> | ar[chive] <idstring> | ldobj /* for specifying /* linker-defined sections */ ; <symspec> ::= sym <idstring> in <inputscn> | sym <idstring> ; EELLSSPPEECC VVaarriiaabblleess The linker uses the values contained in various ELSPEC variables when laying out your program. These variables are as follows: <globals> ::= /* NULL */ | globals set_global ; <set_global ::= <gsize> = <size> | <gbool> = <boolean> ; <gsize> ::= $blocksize | $cachesize | $pagesize | $cachelinesize ; <gbool> ::= $ignoreldgen | $r4kbugfix | $ignoreoverlaps ; BBaassee DDaattaa TTyyppeess The base data types are defined as follows: <size> ::= <number> | <number> K | <number> M ; <address> ::= <number> <number> ::= 0x[0-9a-f]+ /* Hex number */ | 0[0-7]+ /* Octal number */ | [0-9]+ /* decimal number */ ; <boolean> ::= true | false ; <idstring> ::= [a-zA-Z0-9$_.]+ | "<any string>" ; CCoommmmeennttss If the pound character (##) appears in a layout specification (except when within a string specified with quotation marks ("""")), the remainder of the line, including the ## is treated as a comment and is ignored. EEXXAAMMPPLLEESS Example 1. This is the default link specification. Using it should give the same result as not using the --eellssppeecc option on the lldd(1) command. beginseg name text segtype LOAD vaddr 0x10000000 segflags R X segalign 0x10000 contents default endseg beginseg name data segtype LOAD segflags R W X segalign 0x1000 contents default endseg beginseg name noload segtype noload contents default endseg Example 2. This link specification gives the COMMON symbol aa__ an alignment of 128 bytes. This prevents false sharing, among other things. beginseg segtype LOAD segflags R X # vaddr 0x10000000 segalign 0x1000 contents default endseg beginseg segtype LOAD segflags R W # vaddr 0x10011000 segalign 0x1000 contents default beginscn .mybss scntype NOBITS scnflags ALLOC WRITE scnalign 0x80 sym a_ endscn endseg Example 3. If data needs to be loaded relative to the Global Pointer (the ggpprreell area), the ELSPEC file must contain information regarding this data. When this information is missing from the ELSPEC file, the system generates the following messages: ld32: FATAL 173: No gprel area specified in elspec file. Try using "default_gprel" after the data section declaration. See ELSPEC(5) ld32: INFO 152: Output file removed because of error. To correct the file, add the following line: default_gprel Here is the corrected ELSPEC file: beginseg segtype LOAD segflags R W X vaddr 0x88500000 segalign 0x1000 contents beginscn .text scntype PROGBITS scnflags ALLOC EXECINSTR scnalign 0x10 section .text endscn endseg beginseg segtype LOAD segflags R W vaddr 0xa85a5000 segalign 0x1000 contents beginscn .rodata scntype PROGBITS scnflags ALLOC WRITE scnalign 0x8 section .rodata endscn beginscn .rdata scntype PROGBITS scnflags ALLOC WRITE scnalign 0x8 section .rdata endscn beginscn .data scntype PROGBITS scnflags ALLOC WRITE scnalign 0x8 section .data endscn default_gprel # SPECIFIES gprel LOADING beginscn .bss scntype NOBITS scnflags ALLOC WRITE section .bss endscn beginscn .MIPS.options scntype 0x7000000d scnflags ALLOC NOSTRIP scnalign 0x8 section .MIPS.options endscn beginscn .reginfo scntype NOBITS scnflags ALLOC NOSTRIP scnalign 0x8 section .reginfo endscn endseg SSEEEE AALLSSOO eellffdduummpp(1), lldd(1) eellff(4) This man page is available only online.